How to Build a Groupware Connector

Introduction

Various Java standards are emerging in the area of electronic mailing and scheduling. At the moment, the lack of an established standard necessitates the usage of vendor-specific tools or libraries for integrating a particular groupware application. For example, Microsoft Collaborative Data Object is required in order to connect to the Microsoft Exchange server, while the Lotus Domino toolkit is required in order to connect to the Lotus Domino server.

The Groupware framework provides an abstraction of the groupware APIs across different vendors, thereby bringing in a standard for integration with SAP Enterprise Portal. In the current release, the Groupware framework provides abstraction only to calendar data. Abstraction to tasks and contacts is not a part of this release.

Architecture

The Groupware framework provides an abstraction of different groupware applications and provides the necessary APIs for integration with SAP Enterprise Portal. Different groupware applications such as Microsoft Exchange Server or Lotus Domino Server can be integrated by implementing a set of APIs called the transports.

Groupware Architecture

Components

The groupware framework consists of the following parts:

• Calendar Repository Manager
• Groupware Manager
• Transports

Calendar Repository Manager

The calendar repository manager is built using the repository framework. It provides access to calendar items on the groupware server in a manner consistent to any repository item.

Groupware Manager

The Groupware manager is a mediator between the calendar repository manager and the configured transports.

Transports

Transports provide access to the groupware server by implementing the necessary interfaces. The transport performs all read and write operations on the groupware server or groupware store.

Classes and Interfaces

Below is a list of classes and interfaces required to develop a transport.

class/Interface name	package	description
IGroupwareItem	com.sap.ip.collaboration.gw.api.framework.groupware	All items implement this interface.
ICalendarItem	com.sap.ip.collaboration.gw.api.framework.groupware	All calendar items are implementations of ICalenderInterface.
CalendarItemImpl	com.sap.ip.collaboration.gw.api.framework.groupware	Implements ICalendarItem and provides the default implementation and behavior of a calendar item.
ICalendarReadTransport	com.sap.ip.collaboration.gw.api.framework.groupware	This interface provides methods for reading items from the groupware server. Implement this interface to perform any read operation on the groupware server.
ISendTransport	com.sap.ip.collaboration.gw.api.framework.groupware	This interface provides methods for writing/sending items to the groupware server. Implement this interface to perform any write/send operation on the groupware server.
IAttachment	com.sap.ip.collaboration.gw.api.framework.groupware	This interface provides access to attachments.
IGroupwareCredentials	com.sap.ip.collaboration.gw.api.framework.groupware	This interface provides credentials for the groupware server (the user/password configured by the user in the user mapping dialog box for the groupware server or the MYSAP SSO ticket).
TransportType	com.sap.ip.collaboration.gw.api.enum	BOTH - Supports read and write, implements both ICalendarReadTransport and ISendTransport.. READ - Supports only read operations. Implements only ICalendarReadTransport. SEND - Supports only write operations. Implements only ISendTransport.
GroupwareItemType	com.sap.ip.collaboration.gw.api.enum	Determines the type of transport. Types CONTACT and TASK are not supported in this release.
IDateRange	com.sap.ip.collaboration.gw.api.framework.groupware	DateRange class.

Steps for Developing a Transport

Creating a Transport Class

Create a class implementing ICalendarReadTransport and/or ISendTransport depending on the functionality that the transport provides, and import the appropriate classes.

package com.sap.ip.collaboration.gw.impl.transport.test.calendar;

public class TestCalendarTransport
         implements ICalendarReadTransport, ISendTransport {
  // this is just a sample …
}

Setting the Transport Type

The transport type determines whether the transport supports only READ, only SEND or BOTH.

public TransportType getTransportType() {
                 return TransportType.BOTH;
         }

Setting the Supported Item Type

Set the item type that is supported by the transport.

public GroupwareItemType getSupportedItemType() {
         return GroupwareItemType.CALENDAR;
}

Setting the Transport Name

The transport name is used to identify the items belonging to the transport. It is recommended to return the class name in order to ensure uniqueness.

public String getTransportName() {
         return this.getClass().getName();
}

Setting the Description of the Transport

The transport description is used for display purpose in the configuration user interface.

public String getTransportDescription(Locale locale) {
         return "In memory implementation";
}

Initialize and Clean-Up Operations

Implement your initialisation and clean up tasks in:

public void initialize(
         GroupwareManager gwManager, List configuration){
//initialization code goes here
}

public void terminate() throws GroupwareException{
//cleanup code goes here
}

Performing a Search

Implement the following methods:

/**
DateRange:                Date range for performing search
IGroupwareCrendential:    Credential to connect to the groupware server
*/
public List getItemList(DateRange range,
                        IGroupwareCredentials credential)
                 throws GroupwareException {
  //search goes here
  getItemList(range,null,credential);
}

/**
Properties:               Consists of name-value pair that must be used for
                          performing the search. This data is application 
                          specific data and will not be a standard groupware 
                          property
*/
public List getItemList(DateRange range,
                        Properties searchCriteria,
                        IGroupwareCredentials credentials)
                 throws GroupwareException {
  //search goes here
}

The following is a set of mandatory calendar item attributes that must be available in the result set:

• Unique ID
• Subject
• StartDateTime
• EndDateTIme
• Location
• Meeting Type
• All Day - Boolean
• Recurring - Boolean
• Show Time As - Free/busy status

Fetching an item

To return the details of the item identified using the unique identifier, implement:

/**
String:  ID is the unique id that was obtained with the search
*/

public IGroupwareItem getItem(String id, IGroupwareCredentials credential){
 //fetch the item and return…

}

Saving or Sending an Item

To save or send, implement the following. The return value is the unique identifier of the newly created item.

public String save(IGroupwareItem item, IGroupwareCredentials credential)
                 throws GroupwareException {

}

public String send(IGroupwareItem item, IGroupwareCredentials credential)
                 throws GroupwareException {

}

The save operation is used to create 'draft' items, and the send operation is used to send the item to the intended recipients

How to Create a New Item

Use the createNewItem from the GroupwareManager:

calendarItem = (ICalendarItem)gwManager.createNewItem(GroupwareItemType.CALENDAR, this.getClass().getName());

Authentication

There are two ways in which you can provide authentication to your groupware system.

Using the User Mapping iView:

The end user in the portal needs to maintain his or her user and password for the groupware server using the Personalization dialog box in the portal.

For more information on the user mapping iView see References.

The credential information can be obtained from the IGroupwareCredentials object as follows:

IGroupwareCrendentials credentials;
//… get credentials object from the method parameter
// create a java.util.Map object
Map userMap = credentials.getCredentialAttributes();
userName = (String)userMap.get("user");
userPassword = (String)userMap.get("mailserver");

Using SAP SSO2 Ticketing

A recommended alternative to user/password is to use the SAP SSO2 logon ticketing for authentication.

If you are using HttpURLConnection, you can easily get the required cookie (MYSAPSSO2) in your request by using:

IGroupwareCrendentials credentials;
//… get credentials object from the method parameter
HttpURLConnection myUrlConnection;
credentials.enrich(myUrlConnection);

Configurations

The connector can use its own configuration in order to perform the necessary operations. The configuration can be groupware server name, domain and so on. This configuration can be created and maintained using the KM Configuration Framework. The initialize method receives the list of configurations that can be used to perform the necessary operations.

References

[Collaboration Administrator Guide]: help.sap.com -> Select documentation based on desired language -> People Integration -> Collaboration -> Groupware

[User Mapping - End User Guide]: help.sap.com -> Select documentation based on desired language -> People Integration -> Portal -> End User Guide -> Personalizing Your Portal -> Setting Portal Preferences

[User Mapping - Administration Guide]: help.sap.com -> Select documentation based on desired language -> People Integration -> Portal -> Administration Guide -> System Administration -> System Landscape

[KM Configuration Framework]: See the section Config Framework in KMC_Documentation_Eclipse